home *** CD-ROM | disk | FTP | other *** search
/ Aminet 38 / Aminet 38 (2000)(Schatztruhe)[!][Aug 2000].iso / Aminet / misc / math / libalgo.lha / algomath / readme.txt < prev    next >
Encoding:
Text File  |  2000-05-30  |  13.1 KB  |  452 lines
  1. Algomath- c Library   Release 1.0.5   03.2000
  2. -------------------   -------------   -------
  3.  
  4. Algomath is a portable Arithmetic C Library.
  5. All routines have been thoroughly optimised for speed and efficiency,
  6. while at the same time portable C. However optional
  7. fast assembly language alternatives for prime numbers time-critical
  8. routines are also included, particularly for the popular Intel 80x86
  9. range of processors. There is no problem to exclude this code,
  10. -(see COMPILING AND USING ALGOMATH)-
  11.  
  12. The library is tested with DJGPP v2 C-compiler and the
  13. pgcc-2.90.23 compiler. Under CYGNUS the egcs-2.91.57 compiler.
  14. Under VISUALC.
  15. Although it should work on any other system.
  16.  
  17. Download the latest release at:
  18. http://www2.vo.lu/homepages/armand/index.html
  19.                
  20. You are free to do anything you desire with this code,
  21. as long as you give credit where credit is due...
  22.  
  23. For criticism, fixes, suggestions, enhancements, send email to:
  24.  
  25. Armand Turpel: armandt@unforgettable.com
  26.  
  27. Patrick Dostert: patrick.dostert@cie.etat.lu
  28. who helped in optimizing this library
  29.  
  30.  
  31. INDEX
  32. -----
  33.  
  34.      1.FILES IN THIS ARCHIVE
  35.      2.COMPILING AND USING ALGOMATH
  36.      3.DESCRIPTION OF THE FUNCTIONS
  37.      4.HISTORY
  38.      5.LEGAL AND OTHER STUFF
  39.  
  40.  
  41. FILES IN THIS ARCHIVE:
  42. ----------------------
  43.  
  44. algomath.h                
  45.     headerfile
  46. makefile                
  47.     DJGPP makefile
  48. src/*.*                    
  49.     library source code
  50. assembly/src/isprime.asm
  51.     isPrime() assembler source code (nasm)
  52. assembly/obj/isprime.o                
  53.     object code of isPrime()(coff format)
  54. assembly/obj/isprime.obj
  55.     isprime.obj    object code of isPrime()(windows object format)
  56. Readme.txt    
  57.     this file
  58.  
  59.  
  60. COMPILING AND USING ALGOMATH:
  61. -----------------------------
  62.  
  63. Under DJGPP, CYGNUS and VISUALC there should be no problem to compile algomath.
  64.  
  65. Under VISUALC add the following files to your lib project:
  66.     -all files from the /src directory
  67.     -algomath.h
  68.     -assembly/obj/isprime.obj
  69.     
  70. For DJGPP or CYGNUS:
  71.     If you have PGCC installed change in the makefile:
  72.         #PGCC = 1
  73.          to
  74.         PGCC = 1 
  75.     If you have EGCS (on a pentium) installed change in the makefile:
  76.         #EGCS = 1
  77.          to
  78.         EGCS = 1 
  79.     Otherwise disable these two variables:
  80.         #PGCC = 1
  81.         #EGCS = 1
  82.         
  83.     If you dont want to include the assembly
  84.     function(s) in the library,    disable in the makefile:
  85.         ASSEMBLY = 1
  86.          to
  87.         #ASSEMBLY = 1
  88.     In order also change in the algomath.h header file:
  89.         #define USE_ISPRIME_ASM
  90.          to
  91.         /*#define USE_ISPRIME_ASM*/
  92.  
  93. Change to the folder were you have unzip algomath and run make.
  94. After compiling copy lib/libalgo.a to the djgpp/cygnus lib path
  95. and algomath.h to the djgpp/cygnus include path.
  96. To use Algomath, #include <algomath.h> and link with libalgo.a
  97. Example command line: gcc foobar.c -o foobar.exe -lalgo    
  98.  
  99.  
  100. DESCRIPTION OF THE FUNCTIONS:
  101. -----------------------------
  102.  
  103. #######################
  104. ### Initial Rutines ###
  105. #######################
  106.  
  107. int am_init()
  108. -------------
  109.     The function return 0 if there isn't enough memory else 1.
  110.     You !! MUST !! introduce this function once in your code before you
  111.     use any    function.
  112.  
  113.  
  114. void am_exit()
  115. -------------
  116.     if you dont need any more the algomath functions in your code, you
  117.     should call this function. It free some memory that algomath use.
  118.   
  119.  
  120. #######################
  121. ### Numbers Rutines ###
  122. #######################
  123.  
  124. int am_numlength(int n)
  125. -----------------------
  126.     returns the number of digits of a number.
  127.     am_numlength( 65364785 ) return 8
  128.  
  129.  
  130. int am_sumdigits(int n)
  131. -----------------------
  132.      returns the sum of the digits of the number n
  133.      am_sumdigits( 5732 ) returns 17
  134.  
  135.  
  136. int am_sumdigitsalt(int n)
  137. --------------------------
  138.      returns the alternating sum of the digits of the number n
  139.      even digitplaces are substracted, odd digitplaces are added
  140.      am_sumdigitsalt( 5732 ) return 1 because 2-3+7-5
  141.  
  142.  
  143. int am_extract(int n, int x)
  144. ----------------------------
  145.      returns the digit x you want to extract from a number n.
  146.      a negative number will return a negative result.
  147.      if n > 999999999 then the function return n.
  148.  
  149.      am_extract( 648761, 3) return 7
  150.      am_extract( 648761, 5) return 4
  151.      0's before the number (00323443) are also considered.
  152.      am_extract( 8761, 6) return 0
  153.  
  154.      if x is negative, the function convert it to positive.
  155.      if x > 9 then only the last digit is considered.
  156.      ex: x=17 so x=7
  157.  
  158.  
  159. int am_replace(int n, int d1, int d2)
  160. -----------------------------------
  161.      returns the modified number were n is the
  162.      number to modify, d1 is the digit place to modify and
  163.      d2 the digit to put in.
  164.      if n > 999999999 then the function return n.
  165.      if d1 or d2 is negative, the function convert it to positive.
  166.      if d1 or d2 >9 then only the last digit is considered.
  167.      ex: d1=36 so d1=6
  168.  
  169.      am_replace( 47321, 4, 2) return 42321
  170.      am_replace( 47321, 2, 9) return 47391
  171.      0's before the number (00323443) are also considered.
  172.      am_replace( 8761, 6, 2) return 208761
  173.  
  174.  
  175. int am_swap(int n, int d1, int d2)
  176. ----------------------------------
  177.      return the modified number were n is the number to modify,
  178.      d1 the digit place to swap with the d2 digit place.
  179.      if d1 or d2 is negative, the function convert it to positive.
  180.      if d1 or d2 >9 then only the last digit is considered.
  181.      ex: d1=36 so d1=6
  182.      if n > 999999999 then the function return n.
  183.  
  184.      am_swap( 123456 , 2, 4) return 125436
  185.      am_swap( 123456 , 6, 1) return 623451
  186.      0's before the number (00323443) are also considered.
  187.      am_swap( 8761, 6, 2) return 608701
  188.          
  189.  
  190. int am_rotate(int n, int x, int p)
  191. ----------------------------------
  192.      rotates the digits of a number n, x times, in base 10.
  193.      p is number of digits to rotate.
  194.      if p >9 then only the last digit is considered.
  195.      if n > 999999999 then the function return n.
  196.  
  197.      am_rotate(543210,2,5) returns 105432 ( rotate right if x > 0 )
  198.      am_rotate(543210,-2,5) returns 321054 ( rotate left  if x < 0 )
  199.  
  200.      if p > length of the number n then zeros befor the number 
  201.      will be included in the rotation process.
  202.      00543210 = 7 digits
  203.  
  204.      am_rotate(543210,2,7) returns 54321000 ( rotate right if x > 0 )
  205.      am_rotate(543210,-2,7) returns 10005432 ( rotate left  if x < 0 )
  206.  
  207.      if p < length of the number n then only the first p digits
  208.      of the number n will be rotated.
  209.  
  210.      am_rotate(543210,2,3) returns 543102 ( rotate right if x > 0 )
  211.      am_rotate(543210,-2,3) returns 543021 ( rotate left  if x < 0 )
  212.  
  213.  
  214. int am_sort( int n)
  215. -------------------
  216.      " sorts " the digits of a number n
  217.      am_sort( 57834 ) returns 34578
  218.      if n > 999999999 then the function return n.
  219.  
  220.  
  221. ##########################
  222. ### Arithmetic Rutines ###
  223. ##########################
  224.  
  225. int am_sumdivisor(int n)
  226. ------------------------
  227.      returns the sum of all possible divisors of the number n,
  228.      n not included
  229.      am_sumdivisors( 20 ) returns 22 ( = 1 + 2 + 4 + 5 + 10 )
  230.  
  231.  
  232. int am_gcd(int a, int b)
  233. ------------------------
  234.      returns the " greatest common divisor " of two numbers a and b
  235.      am_gcd( 123698745, 147896325) returns 45
  236.  
  237. int am_hailstone(int n)
  238. -----------------------
  239.     This function allows you to investigate hailstone numbers:
  240.     if n == odd then it return n*3+1
  241.     if n== even then it return n/2
  242.     call this function until it return 1.
  243.     if n is negative <0 then the result is also negative.
  244.     if the result is bigger than int or n=0, it return 0 (failure).
  245.     n=77671 is the first number that return 0.
  246.     if you want to investigate all big numbers,I recommend you to use the
  247.     c/c++ miracl library:
  248.     ftp://ftp.compapp.dcu.ie/pub/crypto/miracl.zip
  249.  
  250.     ex.:
  251.     
  252.     n=25267;
  253.     while(n!=1){
  254.         n=am_hailstone(n);
  255.             if(n==0){
  256.                 printf("n is to big\n");
  257.                 exit();
  258.             }
  259.         printf("%d\n",n);
  260.     }
  261.     
  262. #############################
  263. ### Prime Numbers Rutines ###
  264. #############################
  265.  
  266. int am_isprime(int n)
  267. ---------------------
  268.      returns 1 if n is prime else 0
  269.      negative numbers n are also accepted. 
  270.  
  271. int am_prime_ba(int t, int x)
  272. -----------------------------
  273.     If x<0 then the function return the next prime number "befor" the number t.
  274.     If x>0 then the function return the next prime number "after" the number t.
  275.     If x==0 then the function return t
  276.     If t is negative then the result will also be negative.
  277.     
  278. int *am_primes_array(int n, int x)
  279. ----------------------------------
  280.      create x prime numbers from a given number n, and return the
  281.      pointer address. return 0 if there isnt enough memory.
  282.      if n is negative then the primes are also negative.
  283.  
  284.      ex:
  285.      int *pointer , c=0;
  286.  
  287.      if((pointer = am_primes_array(4, 3)) == NULL)
  288.          printf("not enough memory\n");
  289.  
  290.      while( *(pointer+c)){
  291.             printf("%d\n",*(pointer+c));
  292.             c++;
  293.         } 
  294.  
  295.      return *(pointer+0)=5 *(pointer+1)=7 *(pointer+2)=11
  296.      *(pointer+3)=0 !! last variable is always 0 !!
  297.  
  298.      WARNING!!!!!!!
  299.      --------------
  300.      If you dont need any more the prime_array result you should free
  301.      the pointer allocation(s):
  302.      free ( pointer );
  303.  
  304.      take a look at the following code:
  305.  
  306.      for(x=0;x<100000;x++){
  307.          pointer=am_prime_array(x, 1000); 
  308.          /*do some stuff*/
  309.       }
  310.  
  311.      this allocate 100000*1000 int memory!!!!
  312.      so the correct code should be:
  313.  
  314.      for(x=0;x<100000;x++){
  315.          pointer=am_prime_array(x, 1000); 
  316.          /*do some stuff*/
  317.          free(pointer);
  318.       }
  319.  
  320.  
  321. int *am_primes_between(int n1, int n2, int *p)
  322. --------------------------------------
  323.      create prime numbers between two given number n1 and n2, and
  324.      return the pointer address. Store in p the number of primes found.
  325.      return 0 if there isnt enough memory.
  326.      if n1 or n2 = negative then the function convert it to positive.
  327.      It dosen't matter whether n1>n2 or n1<n2. 
  328.      
  329.      ex:
  330.      int *pointer, p, c=0;
  331.  
  332.      if((pointer = am_primes_between(4, 15, &p)) == NULL)
  333.          printf("not enough memory\n");
  334.  
  335.      while( *(pointer+c)){
  336.             printf("%d\n",*(pointer+c));
  337.             c++;
  338.         } 
  339.      
  340.      printf("%d primes found\n", p); print out how many primes found.
  341.  
  342.      print out: 5 7 11 13
  343.      *(pointer+4)=0 !! last last variable is always 0 !!
  344.  
  345.      See WARNING!!!! in am_primes_array()
  346.  
  347.  
  348. int *am_factorize(int n, int *factors)
  349. --------------------------------------
  350.      facrorize a number n and return the pointer address were you
  351.      can find the result. factors contains the number of
  352.      how many factors found. return 0 if there isnt enough memory.
  353.      negative numbers n are also accepted. 
  354.  
  355.      pointer = am_factorize( 20 , &factors) returns:
  356.        factors = 3
  357.        *(pointer+0)=2, *(pointer+1)=2, *(pointer+2) = 5
  358.        *(pointer+3) = 0 !! last variable is always 0 !!
  359.  
  360.      ex:
  361.  
  362.      int *pointer;
  363.      int factors, x = 0;
  364.  
  365.      if((pointer = am_factorize( 20, &factors ))==NULL){
  366.          printf("not enough memory\n");
  367.          exit(0);
  368.        }
  369.      printf("how many factors found: %d\n",factors);
  370.      while(*(pointer+x)){
  371.          printf("%d\n",*(pointer+x);
  372.          x++;
  373.       }
  374.      
  375.      See WARNING!!!! in am_primes_array()
  376.  
  377.  
  378. int am_goldbach(int n,int *d1, int *d2)
  379.  --------------------------------------
  380.     "--'strong' Goldbach's Conjecture
  381.         The Conjecture is, "Every even integer >= 4 is the sum of
  382.         two primes.--"
  383.      Return 0 if n not even else 1.
  384.      n is the even number to test.
  385.      after calling the function, d1 contain the smallest possible prime
  386.      and d2 the second greater prime. if n is negative then d1 and d2 are
  387.      also negative.
  388.  
  389.      ex:
  390.  
  391.      int d1,d2,r,n=16;
  392.  
  393.      r = am_goldbach( 16, &d1, &d2);
  394.      printf("%d = %d + %d\n",n,d1,d2);
  395.  
  396.  
  397. int am_isPrime(unsigned int testnumber)
  398. ------------------------------
  399.     This is the assembly implementation of am_isprime(int n).
  400.     returns 1 if testnumber is prime else 0
  401.     (optimized by Patrick Dostert: patrick.dostert@cie.etat.lu)
  402.  
  403.     If algomath is compiled with #define AM_ISPRIME_ASM
  404.     then algomath use this function for every prime operation.
  405.     But you can include this function as stand alone in your code.
  406.     declare first: extern int am_isPrime(unsigned int);
  407.     and link isprime.o to your program.
  408.  
  409. -----------------------------------------------------------------------
  410.  
  411. HISTORY:
  412. --------
  413.  
  414. Algomath 
  415. 0.9 beta  first release 12.1997
  416. 0.91 beta bugfix release 3.1998
  417. 0.92 beta bugfix release 3.1998
  418. 0.93 beta reviewed and add int am_goldbach(int a,int *p) 4.1998
  419. 1.00 beta rewrite of the prime related routines (better performance) 10.1998
  420. 1.0.1 beta rewrite of the prime related routines
  421.         am_primearray(1,1000000,array)
  422. 1.0.2 beta optimized am_primearray()
  423. 1.0.3 beta add am_prime_init
  424. 1.0.4 complete rewrite the most part of the functions.  11.1999
  425.       fixed some bugs.
  426.       NEW functions:
  427.                     am_exit()
  428.                     am_isPrime() 
  429.                     am_numlength()
  430.                     am_swap()
  431.                     am_replace()
  432.                     am_extract()
  433.                     am_primes_between()
  434. 1.0.5 Tested under CYGNUS and VISUALC
  435.         therefor making some change in the makefile
  436.         add am_isprimeba(int n, int x)
  437.         add am_hailstone(int n)
  438.         
  439.  
  440. LEGAL AND OTHER STUFF:
  441. ----------------------
  442.  
  443. Pentium is a (registered) trademark of Intel, http://www.intel.com
  444. DJGPP is the MSDOS-port of the famous GNU-C compiler, http://www.delorie.com
  445. MSDOS is a (registered) trademark of Microsoft, http://www.microsoft.com
  446. for info on GNU software see http://www.gnu.org
  447.  
  448.  
  449. ------------------------------------------------------------------------------
  450.  
  451.   Luxembourg, 11.1999,
  452.   Armand Turpel